JWT Tokens

Learn how to obtain and use JWT tokens for API authentication

Overview

JSON Web Tokens (JWT) are the primary authentication mechanism for the Yucatan Public Works API. After successful login, you’ll receive a JWT token that must be included in all subsequent API requests.

Obtaining a Token

To obtain a JWT token, send a POST request to the /auth/login endpoint with your credentials.

Endpoint

POST /auth/login

Request Body

email · string · required

User’s email address

password · string · required

User’s password

Example Request

cURL

curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "password": "admin123"
  }'

Success Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI3YzNhNjg5MS0xMjM0LTU2NzgtOWFiYy1kZWYwMTIzNDU2NzgiLCJlbWFpbCI6ImFkbWluQHl1Y2F0YW4uZ29iLm14Iiwicm9sZXMiOiJhZG1pbiIsImlhdCI6MTYxNjIzOTAyMn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "user": {
    "id": "7c3a6891-1234-5678-9abc-def012345678",
    "email": "[e-mail]",
    "roles": "admin",
    "mustChangePassword": false
  }
}

Error Response

If the credentials are invalid, you’ll receive a 401 Unauthorized response:

{
  "statusCode": 401,
  "message": "Credenciales inválidas",
  "error": "Unauthorized"
}

Token Structure

JWT tokens consist of three parts separated by dots (.):

header.payload.signature

Token Payload

The token payload contains the following claims:

sub · string

Subject - The user’s unique ID (UUID)

email · string

The user’s email address

roles · string

The user’s role (e.g., “admin” or “user”)

iat · number

Issued At - Timestamp when the token was created

Example Decoded Payload

{
  "sub": "7c3a6891-1234-5678-9abc-def012345678",
  "email": "[e-mail]",
  "roles": "admin",
  "iat": 1616239022
}

The token payload is generated in auth.service.ts:27-31 using the user’s information.

Using Tokens in API Requests

Once you have a token, include it in the Authorization header of your requests using the Bearer scheme.

Authorization Header Format

Authorization: Bearer <your_access_token>

Example Requests

cURL - Get All Obras

curl -X GET http://localhost:3000/obras \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Token Validation

The API validates tokens using the Passport JWT strategy. The validation process:

1. Extracts the token from the Authorization header
2. Verifies the signature using the secret key
3. Checks expiration - expired tokens are rejected
4. Decodes the payload and attaches user info to the request

jwt.strategy.ts:15-18

async validate(payload: any) {
  return { userId: payload.sub, email: payload.email, roles: payload.roles };
}

If the token is missing, invalid, or expired, the API will return a 401 Unauthorized response.

Token Expiration

The current implementation sets token expiration based on the JWT configuration. When a token expires:

• The API will reject the token with a 401 Unauthorized response
• The client must request a new token by logging in again

jwt.strategy.ts:10

ignoreExpiration: false, // Tokens must not be expired

Currently, the API does not implement token refresh functionality. Users must log in again to obtain a new token after expiration.

Security Best Practices

Store tokens securely

• Never store tokens in localStorage (vulnerable to XSS attacks)
• Use httpOnly cookies or secure session storage
• Consider using memory storage for highly sensitive applications

Handle token expiration gracefully

• Implement automatic re-authentication when tokens expire
• Show user-friendly messages for expired sessions
• Consider implementing token refresh for better UX

Protect your tokens

• Never expose tokens in URLs or logs
• Use HTTPS in production to prevent token interception
• Implement token revocation for compromised accounts

Related Resources

Authentication Overview

Learn about the authentication system

Roles & Permissions

Understand role-based access control